<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel=stylesheet type="text/css" href="../styles.css">
<title>DocFlex/XML (Kit) - XSDDoc - Frequently Asked Questions</title>

<script language = "JavaScript">
  function popupWindow(url, width, height)
  {
    var max_width = screen.width - 8;
    var max_height = screen.height - 64;

    var resizable = false;

    if (height > max_height)
    {
      height = max_height;
      width = width + 20;
      resizable = true;
    }

    if (width > max_width)
    {
      width = max_width;
      resizable = true;
    }

    var left = (max_width - width) / 2;
    var top = (max_height - height) / 2;

    var winName = width + "x" + height;
    var winParms = "top=" + top + ",left=" + left + ",height=" + height + ",width=" + width +
                   ",toolbar=no,location=no,directories=no,status=no,menubar=no," +
                   (resizable ? ",resizable=yes,scrollbars=yes" : ",resizable=no,scrollbars=no");

    var win = window.open(url, winName, winParms);
    if (parseInt(navigator.appVersion) >= 4) { win.window.focus(); }
  }
</script>

</head>

<body>

<h1>
  DocFlex/XML (Kit) - XSDDoc - Frequently Asked Questions
</h1>

<!-- TABLE OF CONTENTS -->
<ol>
  <li><a href="#getting_started">How to get started?</a></li>
  <li><a href="#how_fast">How fast does it work?</a></li>
  <li><a href="#gen_html">How to generate HTML documentation?</a>
      <ul>
        <li><a href="#gen_html.framed">Framed HTML</a></li>
        <li><a href="#gen_html.single_file">Single-file HTML</a></li>
        <li><a href="#gen_html.params">Template Parameters</a></li>
        <li><a href="#gen_html.options">HTML Options</a></li>
      </ul>
  </li>
  <li><a href="#gen_rtf">How to generate RTF documentation?</a>
      <ul>
        <li><a href="#gen_rtf.params">Template Parameters</a></li>
        <li><a href="#gen_rtf.options">RTF Options</a></li>
      </ul>
  </li>
  <li><a href="#multiple_schemas">How to generate a single documentation by multiple XML schemas?</a></li>
  <li><a href="#pathname_with_spaces">How to specify a schema file pathname with spaces?</a></li>
  <li><a href="#integration_with_ant">How to integrate XSDDoc with Apache Ant?</a></li>
  <li><a href="#adding_comments">How to add descriptions/comments into my XML schema?</a></li>
  <li><a href="#rendering_line_breaks">How to enable/disable interpreting line breaks in my comments?</a></li>
  <li><a href="#xhtml">How to format my comments using XHTML?</a>
      <ul>
        <li><a href="#xhtml.about">What is XHTML?</a></li>
        <li><a href="#xhtml.usage">How to use XHTML?</a></li>
        <li><a href="#xhtml.images">How to insert images?</a></li>
        <li><a href="#xhtml.params_and_options">Parameters & options related to XHTML and images</a></li>
      </ul>
  </li>
  <li><a href="#invalid_doc">There is some oddity in the documentation I've generated. What might be wrong?</a></li>
  <li><a href="#xmlschema.resources">Where can I learn more about XML schemas?</a></li>
</ol>
<!-- END TABLE OF CONTENTS -->

<h2>
  <a name="getting_started"></a>
  1.&nbsp; How to get started?
</h2>

<p>You can start generating your XML Schema documentation almost immediately.
Just follow this instruction:

<ol>
<li class="mrg8">
  Download <a href="../about.html">DocFlex/XML</a> or
  <a href="../about.html#freeware_edition">DocFlex/XML (Kit)</a> (<b>freeware!</b>)
  from the <a href="http://www.filigris.com/downloads/" target="_blank">downloads</a> page.
</li>
<li class="mrg8">
  Edit <code><b>generator.bat</b></code> to specify the 'JRE' variable according
  to the location of Java 5 or Java 1.4.x installed on your system.
  <p class="mrg8">
  If you don't have Java 5 or Java 1.4.x installed on your system, you can freely
  download and install Java Runtime Environment (JRE) version 1.5.x
  from Sun Java Technology web-site: <a href="http://java.sun.com/" target="_blank">http://java.sun.com</a>
</li>
<li class="mrg8">
  Run <code><b>generator.bat</b></code>. You will see the
  <a href="about.html#generator_gui">Generator Dialog</a>,
  as the one shown on this screenshot:
  <p class="mrg8">
  <img src="images/generator_dialog.png" alt="Generator Dialog" border="0">
</li>
<li class="mrg8">
  In the <b>&ldquo;Template&rdquo;</b> field, select
  <a href="about.html#XSDDocFrames.tpl"><code>XSDDocFrames.tpl</code></a> template
  to generate framed <a href="about.html#output.html">HTML documentation</a> or
  <a href="about.html#XSDDoc.tpl"><code>XSDDoc.tpl</code></a> template to generate
  single-file <a href="about.html#output.rtf">RTF documentation</a>.
</li>
<li class="mrg8">
  In the <b>&ldquo;XML File(s)&rdquo;</b> field, specify one or many XSD files from
  which you want to generate your XML schema documentation.
  When multiple files are specified, make sure that each pathname or URL is enclosed in double quotes.
</li>
<li class="mrg8">
  In the <b>&ldquo;Output format&rdquo;</b> field, select <b>HTML</b> or <b>RTF</b> format
  (RTF will work only with <a href="about.html#XSDDoc.tpl"><code>XSDDoc.tpl</code></a>
  template!).
</li>
<li class="mrg8">
  Click <b>&ldquo;Run&rdquo;</b> button to start generator.
  For a huge schema (or, perhaps, on a slow computer), wait some time while the generator
  processes your schema.
</li>
<li class="mrg8">
  That's all. Enjoy an incredible quality
  XML Schema <a href="about.html#output">documentation</a>
  you won't produce with anything else!
</li>
</ol>

<h2>
  <a name="how_fast"></a>
  2.&nbsp; How fast does it work?
</h2>

Even though the entire XML Schema Documentation Generator is implemented
as a <a href="about.html#xsddoc_templates">set of templates</a>,
which adds an additional level of interpretation, we have passed a very long way
of optimizations.
<p>
Now, by its performance, the result documentation generator
(i.e. the templates plus the template interpreter) may well rival with anything
written directly in Java or C++.
However, unlike the general programming language, the template approach gives
an incredible programming flexibility and integrity.
The things that may take days or weeks of programming and debugging in Java
can be done in a few minutes using
<a href="http://www.filigris.com/products/docflex/about.php" target="_blank">DocFlex templates</a>!

<p>
The performance statistics is the following.
<p>
Processing a typical little XML Schema you would normally find in most of applications (e.g. see
"<a href="http://www.filigris.com/products/docflex_xml/samples/sales_report.php" target="_blank">Sales Report</a>" sample)
on an ordinary modern PC (e.g. based on Intel Pentium 4 or AMD Athlon) may take just
a few seconds (most of which will be just launching the JVM itself).
<p>
The biggest set of XML schemas, for which we have ever generated a single HTML documentation so far, is
"<a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/index.php#html.eclipse-uml2" target="_blank">XML Schemas for Eclipse UML2</a>".
Those schemas define in total 800+ separately documented components (some of which specify very
complicated content models). In the recent test, it took only 150 seconds on a pretty ordinary computer
to generate the entire
<a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/eclipse_uml2/" target="_blank">HTML documentation</a>
consisting of 841 separate HTML files!
<p>
See <a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/" target="_blank">DocFlex/XSD | Examples</a>
for more demo documentations and statistics about other big XML schemas.

<h2>
  <a name="gen_html"></a>
  3.&nbsp; How to generate HTML documentation?
</h2>

<h3>
  <a name="gen_html.framed"></a>
  Framed HTML
</h3>

To generate a multi-framed HTML (Javadoc-like) XML Schema documentation, basically, you should:

<ol>
  <li>Start the generator (run <code>generator.bat</code>).</li>
  <li>
    Select <a href="about.html#XSDDocFrames.tpl">XSDDocFrames.tpl</a>
    template in the <a href="about.html#generator_gui">Generator Dialog</a>.
  </li>
  <li>Specify one or many source XML schema (XSD) files.</li>
  <li>Select HTML output format.</li>
  <li>Click "Run" button.</li>
</ol>

<h3>
  <a name="gen_html.single_file"></a>
  Single-file HTML
</h3>

Sometimes you may want to generate your entire XML Schema documentation as a single HTML file
(including <a href="#xhtml.images">images</a> and anything else). That's easy to do:

<ol>
  <li>Start the generator (run <code>generator.bat</code>).</li>
  <li>
    Select <a href="about.html#XSDDoc.tpl">XSDDoc.tpl</a>
    template in the <a href="about.html#generator_gui">Generator Dialog</a>.
  </li>
  <li>Specify one or many source XML schema (XSD) files.</li>
  <li>Select HTML output format.</li>
  <li>Click "Run" button.</li>
</ol>

<h3>
  <a name="gen_html.params"></a>
  Template Parameters
</h3>

There are also some parameters of
<a href="about.html#xsddoc_templates">XSDDoc</a> templates
(as well as HTML output format <a href="#gen_html.options">options</a>)
that you may check before starting the generation to ensure a better quality output.
<p>
To set the template parameters, click <b>&ldquo;Params&rdquo;</b> button.
The <a href="about.html#param_inspector">Parameter Inspector</a>
dialog will appear filled with the parameters declared in the selected template
as shown on the following screenshot (click to see the full parameter list):

<blockquote>
<a href="javascript:popupWindow('images/param_inspector.html',488,3250)"><img src="images/param_inspector_s.png" alt="Template Parameters" border="0"></a>
</blockquote>

When you start everything for the first time, all parameters will have their default values
specified in the template. As you set some parameters and close the inspector dialog,
the values of the parameters you have set will be stored (along with the parameter names)
in the <a href="../doc.html#generator.config">generator.config</a> file.
Further, the generator will use those values from that file. So will be when you open the
<a href="about.html#param_inspector">Parameter Inspector</a>
dialog next time. The template parameters, whose names match those found in the
<a href="../doc.html#generator.config">generator.config</a> file,
will be initialized with the corresponding values stored in that file.
That's why when you want to generate something different than the previous time,
you may need to change the template parameters appropriately.
<p>
To generate HTML documentation, the following parameters of
<a href="about.html#XSDDoc.tpl">XSDDoc.tpl</a> and
<a href="about.html#XSDDocFrames.tpl">XSDDocFrames.tpl</a>
templates may be important:

<p>
<table width="100%" border="1" cellspacing="1" cellpadding="4">

<tr align="center">
  <th><b>Parameter</b></th>
  <th><b>Comment</b></th>
</tr>

<tr valign="top">
  <td>Documentation Title</td>
  <td>
    Here, you can specify the title to be placed at the top of the documentation overview.
  </td>
</tr>

<tr valign="top">
  <td><b><i>Sections</i></b></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Annotation</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Process XHTML tags</p></td>
  <td>
    Check this parameter, when your schemas contain
    <a href="#adding_comments">annotations</a>
    preformatted with <a href="#xhtml">XHTML</a>.
    See also recommendation about <a href="#gen_html.options">HTML options</a>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Include images<br>Copy images</p></td>
  <td>
    Check these parameters, when some of your
    <a href="#adding_comments">annotations</a> include images.
    See also: <a href="#xhtml.images">How to insert images?</a>
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>XML Source</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px"><b><i>Enclose in Box</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:30px">
    Schemas<br>Components<br>Attribute&nbsp;Detail<br>Content&nbsp;Element&nbsp;Detail
  </p></td>
  <td>
    These parameters specify if the various fragments of the reproduced XML source should
    be enclosed in boxes (with the light-gray background).
    In the case of HTML documentation, this will look good and make the XML source fragments look different.
    So, you can set all those parameters <code>true</code>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Attribute&nbsp;Detail</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Component's only</p></td>
  <td>
    This parameter controls if the
    <a href="about.html#doc.attribute_detail">Attribute Detail</a>
    section of each
    <a href="about.html#doc.blocks.component">Component Documentation</a>
    should include details about all attributes associated with this component or only those directly
    defined in it (different attributes may be inherited from other components,
    from which the given component is derived).
    <p class="mrg8"></p>
    In the case of HTML documentation, the details generated for each attribute will be hyperlinked
    from anywhere that attribute is mentioned (for instance, from the
    <a href="about.html#doc.xml_rep">XML Representation Summary</a>).
    So, in order to make the result documentation more compact, it is better
    to have this parameter selected.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Content&nbsp;Element&nbsp;Detail</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Component's only</p></td>
  <td>
    This parameter controls the same things as the parameter above, however now this is
    about documenting the definitions of the content elements associated with the component.
    In the case of HTML documentation, it is also better to select this parameter.
  </td>
</tr>

</table>

<h3>
  <a name="gen_html.options"></a>
  HTML Options
</h3>

Besides the <a href="#gen_html.params">template parameters</a>,
there are also the <b>output format options</b>.
They control the similar things. However, the difference is that unlike the template parameters,
the support of the options is hardcoded in the template interpreter itself.

<p>
When you click <b>&ldquo;Options&rdquo;</b> button (with the HTML format selected at that),
you will see the <b>HTML Option Inspector</b> dialog, like shown on the screenshot:
<blockquote>
<img src="../images/html_option_inspector.png" alt="HTML Option Inspector" border="0">
</blockquote>

<p>
The following options may by particularly important for the generation of HTML documentation:

<p>
<table width="100%" border="1" cellspacing="1" cellpadding="4">

<tr align="center">
  <th><b>Option</b></th>
  <th><b>Comment</b></th>
</tr>

<tr valign="top">
  <td>Add&nbsp;Mark&nbsp;of&nbsp;the&nbsp;Web</td>
  <td>
    Check this option when the generated documentation is mostly intended for
    viewing on your local system. This will force the generator to add
    a special "Mark of the Web" (MOTW) comment in every generated HTML file.
    <p class="mrg8"></p>
    Without that comment, on each opening of a new HTML file (e.g. when clicking on a hyperlink),
    Microsoft Internet Explorer may pop up a security information bar saying that it has restricted
    that file from showing active content. The "active content" in that case is
    a few JavaScript operators used in the framed HTML documentation generated by DocFlex.
    So, to avoid all that hassle, just set this option <code>true</code>.
  </td>
</tr>

<tr valign="top">
  <td>Render&nbsp;embedded&nbsp;HTML</td>
  <td>
    Select this option (together with "Process XHTML tags" template parameter),
    when you want to show in the generated documentation the <a href="#xhtml">XHTML</a> formatting
    specified in your <a href="#adding_comments">annotations</a>.
  </td>
</tr>

<tr valign="top">
  <td>Render&nbsp;line&nbsp;breaks</td>
  <td>
    Select this option, when you want the line breaks specified in your original
    <a href="#adding_comments">annotation</a> texts to be interpreted
    (with &lt;BR&gt; tags) in the generated HTML output.
    <p class="mrg8"></p>
    Note: When you use <a href="#xhtml">XHTML</a> to format your
    <a href="#adding_comments">annotations</a>, this option may need to be unselected.
  </td>
</tr>

</table>

<h2>
  <a name="gen_rtf"></a>
  4.&nbsp; How to generate RTF documentation?
</h2>

To generate a single-file XML Schema documentation in RTF format, you should:

<ol>
  <li>Start the generator (run <code>generator.bat</code>).</li>
  <li>
    Select <a href="about.html#XSDDoc.tpl">XSDDoc.tpl</a>
    template in the <a href="about.html#generator_gui">Generator Dialog</a>.
  </li>
  <li>Specify one or many source XML schema (XSD) files.</li>
  <li>Select RTF output format.</li>
  <li>Click "Run" button to start generation.</li>
</ol>

<h3>
  <a name="gen_rtf.params"></a>
  Template Parameters
</h3>

Before starting the generation, we also recommend paying attention to the following
parameters of <a href="about.html#XSDDoc.tpl">XSDDoc.tpl</a> template:

<p>
<table width="100%" border="1" cellspacing="1" cellpadding="4">

<tr align="center">
  <th><b>Parameter</b></th>
  <th><b>Comment</b></th>
</tr>

<tr valign="top">
  <td>Documentation Title</td>
  <td>
    Here, you can specify the title to be placed on the documentation first page.
  </td>
</tr>

<tr valign="top">
  <td><b><i>Sections</i></b></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Annotation</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Process XHTML tags</p></td>
  <td>
    Check this parameter, when your schemas contain
    <a href="#adding_comments">annotations</a>
    preformatted with <a href="#xhtml">XHTML</a>.
    See also recommendations about <a href="#gen_rtf.options">RTF options</a>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Include images</p></td>
  <td>
    Check this parameter, when some of your
    <a href="#adding_comments">annotations</a> include images.
    See also: <a href="#xhtml.images">How to insert images?</a>
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>XML Source</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px"><b><i>Enclose in Box</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:30px">
    Schemas<br>Components
  </p></td>
  <td>
    These parameters specify if the XML source of the whole XML schema
    and the fragments defining each component should be enclosed in boxes.
    <p class="mrg8"></p>
    Since in RTF documentation, those XML source fragments may be big
    and occupy entire page width, they will look better without boxes
    (and a background color). So, we recommend setting those parameters
    <code>false</code>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Attribute&nbsp;Detail</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Component's only</p></td>
  <td>
    This parameter controls if the
    <a href="about.html#doc.attribute_detail">Attribute Detail</a>
    section of each
    <a href="about.html#doc.blocks.component">Component Documentation</a>
    should include details about all attributes associated with this component or only those directly
    defined in it (different attributes may be inherited from other components,
    from which the given component is derived).
    <p class="mrg8"></p>
    In the case of RTF output, you may want to generate a reduced version of the documentation
    (because the full one with all possible details may stretch to hundreds of pages).
    To get every attribute documented, you will need to set this parameter <code>false</code>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Content&nbsp;Element&nbsp;Detail</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:20px">Component's only</p></td>
  <td>
    This parameter controls the same things as the parameter above, however now this is
    about documenting the definitions of the content elements associated with the component.
    In the case of RTF documentation, you may also need to have this parameter unselected.
  </td>
</tr>

<tr valign="top">
  <td><b><i>Formatting</i></b></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Allow nested tables</p></td>
  <td>
    This parameter controls whether the generated output may contain nested tables.
    <p class="mrg8"></p>
    <a href="about.html#xsddoc_templates">XSDDoc templates</a>
    frequently use tables as layouts in order to fit data better on a page.
    In certain cases, however, this leads to the situation when one table is nested into a cell
    of another table. For some RTF reader, this may cause a problem.
    <p class="mrg8"></p>
    Although RTF specification since v1.6 does support nested tables (as well as MS Word 2000 and the later),
    some modern and important RTF readers (such as OpenOffice.org 2.0) break on them.
    <p class="mrg8"></p>
    To work around this problem, all XSDDoc templates that use nested tables also
    contain alternative sections without them. Such sections will be activated instead of
    the primary ones, when this parameter is unchecked. Although, without nested tables
    some pieces of the documentation may look less compact and sleek, this still allows generating
    a quite decently looking output.
    <p class="mrg8"></p>
    Please, uncheck this parameter when your destination RTF reader has problems with nested tables!
  </td>
</tr>

<tr valign="top">
  <td><b><i>Pagination</i></b></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Generate page references</p></td>
  <td>
    This parameter specifies whether to generate the cross-reference page numbers, which
    serve as substitutions for some hyperlinks in the printed documentation to help
    navigating it.
    <p class="mrg8"></p>
    If you do not need those references (and feel that the generated output is
    too littered with them) you may uncheck this parameter.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px"><b><i>Start&nbsp;from&nbsp;new&nbsp;page</i></b></p></td>
  <td>parameter group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:30px">
    Namespace&nbsp;Overview<br>Schema&nbsp;Overview<br>Component&nbsp;Documentation
  </p></td>
  <td>
    These parameters control which documentation blocks should be started from a new page.
  </td>
</tr>

</table>

<h3>
  <a name="gen_rtf.options"></a>
  RTF Options
</h3>

Besides the <a href="#gen_rtf.params">template parameters</a>,
there are also the <b>output format options</b>.
They control the similar things. However, the difference is that unlike the template parameters,
the support of the options is hardcoded in the template interpreter itself.

<p>
When you click <b>&ldquo;Options&rdquo;</b> button (with the RTF format selected at that),
you will see the <b>RTF Option Inspector</b> dialog, like shown on the screenshot:
<blockquote>
<img src="../images/rtf_option_inspector.png" alt="RTF Option Inspector" border="0">
</blockquote>

<p>
Please, pay attention to the following options:

<p>
<table width="100%" border="1" cellspacing="1" cellpadding="4">

<tr align="center">
  <th width="1%"><b>Option</b></th>
  <th width="99%"><b>Comment</b></th>
</tr>

<tr valign="top">
  <td><b><i>Styles</i></b></td>
  <td>option group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Include&nbsp;paragraph&nbsp;styles<br>Include&nbsp;character&nbsp;styles</p></td>
  <td>
    These two options specify whether paragraph/character styles should be included in the generated RTF.
    <p class="mrg8"></p>
    When the option is selected, for each style defined in templates a corresponding RTF style
    will be generated and references to it will be inserted in every location where that style is used.
    <p class="mrg8"></p>
    When the option is unselected, no specific style information will get into the RTF.
    However, any formatting specified in the template styles will be used anyway.
    <p class="mrg8"></p>
    You may need to disable the inclusion of style information in some situations,
    when the generated RTF is intended primarily for using in non MS Word applications.
    Certain RTF readers, although appear to understand most of the RTF settings quite well,
    nevertheless, may produce such a mess with the styles imported from an RTF that the result document
    may look considerably distorted.
    <p class="mrg8"></p>
    Here are the option values recommended for different destination applications:
    <p class="mrg8"></p>
    <table border="1" cellspacing="1" cellpadding="3">
      <tr>
        <th><b>Open with</b></th>
        <th><b>Option value</b></th>
      </tr>
      <tr valign="bottom">
        <td>MS Word</td>
        <td><code>true</code></td>
      </tr>
      <tr valign="bottom">
        <td>OpenOffice.org</td>
        <td><code>false</code></td>
      </tr>
    </table>
  </td>
</tr>

<tr valign="top">
  <td><b><i>Text</i></b></td>
  <td>option group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Render&nbsp;embedded&nbsp;HTML</p></td>
  <td>
    Select this option (together with "Process XHTML tags" template parameter),
    when you want to show in the generated documentation the <a href="#xhtml">XHTML</a> formatting
    specified in your <a href="#adding_comments">annotations</a>.
  </td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Render&nbsp;line&nbsp;breaks</p></td>
  <td>
    Select this option, when you want the line breaks specified in your original
    <a href="#adding_comments">annotation</a> texts to be interpreted
    with new lines in the generated RTF output.
    <p class="mrg8"></p>
    Note: When you use <a href="#xhtml">XHTML</a> to format your
    <a href="#adding_comments">annotations</a>, this option may need to be unselected.
  </td>
</tr>

<tr valign="top">
  <td><b><i>Images</i></b></td>
  <td>option group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Store&nbsp;graphics&nbsp;in&nbsp;RTF</p></td>
  <td>
    Select this option, when you want all images to be stored directly in the generated
    RTF. In that case, the result will be a single file.
    If unchecked, the image files will be saved separately in an 'xxx_files' subdirectory
    near the document. Only references to them will be inserted in the generated RTF output.
    This may reduce the result file size, particularly when some big images are repeating.
    <p class="mrg8"></p>
    See also: <a href="#xhtml.images">How to insert images?</a>
  </td>
</tr>

<tr valign="top">
  <td><b><i>Other options</i></b></td>
  <td>option group</td>
</tr>

<tr valign="top">
  <td><p class="mrg0" style="margin-left:10px">Tune&nbsp;output&nbsp;for&nbsp;MS&nbsp;Word</p></td>
  <td>
    When this option is <code>true</code>, the generator will adjust some RTF formatting
    settings specifically for MS Word.
    <p class="mrg8"></p>
    Although Microsoft is the originator of RTF format, the MS Word itself appears to have
    some oddities of rendering certain RTF settings, even though those settings may well
    follow the RTF specification. For instance, when displaying the paragraph or table borders,
    their horizontal positions may be shifted (e.g. when MS Word interprets horizontal margins
    of a paragraph, it draws the paragraph borders and paddings within the specified margin space
    but not within the paragraph content as it might be natural).
    <p class="mrg8"></p>
    To overcome this, in such cases, we adjust the initial dimensions in the opposite way
    so as the result formatting would look properly in MS Word (e.g. to make the actual
    paragraph margin look as intended the margin width specified in RTF is increased by the
    paragraph border and padding widths).
    <p class="mrg8"></p>
    However, when you generate RTF to display it primarily not in MS Word but rather
    in different viewers or editors (e.g. OpenOffice.org under Linux), which interpret
    the original RTF specification more literally, those specific adjustments may cause
    a visible distortion of the intended formatting of the result document.
    In such cases, we recommend to uncheck this option.
    <p class="mrg8"></p>
    Values of this option recommended for different destination applications:
    <p class="mrg8"></p>
    <table border="1" cellspacing="1" cellpadding="3">
      <tr>
        <th><b>Open with</b></th>
        <th><b>Option value</b></th>
      </tr>
      <tr valign="bottom">
        <td>MS Word</td>
        <td><code>true</code></td>
      </tr>
      <tr valign="bottom">
        <td>OpenOffice.org</td>
        <td><code>false</code></td>
      </tr>
    </table>
  </td>
</tr>

</table>


<h2>
  <a name="multiple_schemas"></a>
  5.&nbsp; How to generate a single documentation by multiple XML schemas?
</h2>

You can easily generate a single (common) XML schema documentation by any number
of different XML schema files.
At that, when a component from a schema A is used somewhere in a schema B,
this will be mentioned and reflected with cross-hyperlinks in the corresponding sections
of the documentation parts generated by both schemas.
<p>
Let's suppose, we have an XML schema called "Products.xsd", which contains the following definition:
<blockquote>
  <pre>&lt;xs:element name="ProductId" type="xs:integer"/&gt;</pre>
</blockquote>
Now, we want to generate the documentation for that schema and integrate it together
with the documentation generated for the
<a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/index.html" target="_blank">"XML&nbsp;Schema&nbsp;for&nbsp;XML&nbsp;Schemas&rdquo;</a>,
which is the schema (found at
<code><a href="http://www.w3.org/2001/XMLSchema.xsd" target="_blank">www.w3.org/2001/XMLSchema.xsd</a></code>)
that defines the W3C XML Schema language itself.
<p>
To do this, in the <b>&ldquo;XML File(s)&rdquo;</b> field of the
<a href="about.html#generator_gui">Generator Dialog</a>,
we should specify the following line:
<blockquote>
  <pre>Products.xsd http://www.w3.org/2001/XMLSchema.xsd</pre>
</blockquote>
or the following:
<blockquote>
  <pre>"Products.xsd" "http://www.w3.org/2001/XMLSchema.xsd"</pre>
</blockquote>
which is the same.

<p>
After finishing of the generation, we will receive a documentation containing the full details
of both "Products.xsd" and "XMLSchema.xsd" schemas.
In addition, every type that is defined in "XMLSchema.xsd" and used in
"Products.xsd" will be hyperlinked to its
<a href="about.html#doc.blocks.component">Component Documentation</a>
generated by "XMLSchema.xsd". For example:

<blockquote>
  <pre>&lt;xs:element name="ProductId" type="<a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/simpleTypes/integer.html" target="_blank">xs:integer</a>"/&gt;</pre>
</blockquote>

Moreover, in that case, the
<a href="about.html#doc.comp_lists.usage">Usage Locations Report</a>
of the <code>"xs:integer"</code> type will also contain mentioning of the <code>"ProductId"</code>
element, which is defined in "Products.xsd" schema and uses this type.

<h2>
  <a name="pathname_with_spaces"></a>
  6.&nbsp; How to specify a schema file pathname with spaces?
</h2>

When some of your XML schema file pathnames contain spaces, to specify them to the generator,
you need to enclose every such a pathname in double quotes. For example:
<blockquote>
<code>"c:\My XML Projects\schemas\products.xsd"</code>
</blockquote>

This should be done both in the
<a href="about.html#generator_gui">Generator Dialog</a>
and on the generator <a href="../doc.html#generator">command line</a>.

<h2>
  <a name="integration_with_ant"></a>
  7.&nbsp; How to integrate XSDDoc with Apache Ant?
</h2>

Please, see
<a href="../doc.html#integration_with_ant">DocFlex/XML | Documentation | Tips | Integration with Apache Ant</a>.

<h2>
  <a name="adding_comments"></a>
  8.&nbsp; How to add descriptions/comments into my XML schema?
</h2>

The <a href="http://www.w3.org/XML/Schema" target="_blank">W3C XML Schema</a>
language defines a special
<b><code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code></b>
element that allows adding comments into any XML Schema.
<p>
Precisely, the <code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
element is a container of two other elements:
<ol>
<li class="mrg8">
  <b><code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/appinfo.html" target="_blank">&lt;xs:appinfo&gt;</a></code></b>,
  which allows adding some additional custom instructions that may be used by a particular application
  that processes the schema.
</li>
<li class="mrg8">
  <b><code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code></b>,
  where your comment text should be actually inserted.
</li>
</ol>

In the following example, the string <i>"Complete List of all Salutations"</i>
is the comment added in the definition of the <code>"SalutationType"</code> type using
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
element:
<p>
<TABLE BGCOLOR="#F5F5F5" CELLSPACING="0" CELLPADDING="7" BORDER="0" CLASS="brdr1">
<TR>
<TD CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:simpleType</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">SalutationType</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">Complete List of all Salutations</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:restriction</SPAN> <SPAN CLASS="f2">base</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">xs:string</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:enumeration</SPAN> <SPAN CLASS="f2">value</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">MR.</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:enumeration</SPAN> <SPAN CLASS="f2">value</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">MS.</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:enumeration</SPAN> <SPAN CLASS="f2">value</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">MRS</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:restriction</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV><DIV><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:simpleType</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
</TD>
</TR>
</TABLE>
</p>

The <a href="about.html#xsddoc_templates">XSDDoc</a> templates can process such an
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
element and generate by its content the "Annotation" section of the
<a href="about.html#doc.blocks.component">Component Documentation</a>. Click
<a href="http://www.filigris.com/products/docflex_xml/samples/files/sales_xsd_files/schemas/sales_xsd/simpleTypes/SalutationType.html" target="_blank">here</a>
to see how it will look.
<p>
Almost all XML Schema elements can include
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
elements (click on the link to see precisely which).
However, not all of them are processed by <a href="about.html#xsddoc_templates">XSDDoc</a> templates.
Which exactly are processed you can see in this section:
<a href="about.html#proc.ann.elements" class="nowrap">About | Processing of &lt;xs:annotation&gt; elements</a>.
<p>
Within the <code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element, you can write any text containing any number of lines.
Note also that some XML markup character must be encoded with the corresponding entities:
<p>
<table border="1" cellspacing="1" cellpadding="3">
<tr>
  <th><b>Character</b></th>
  <th><b>Entity</b></th>
</tr>
<tr>
  <td align="center"><code>&lt;</code></td>
  <td><code>&amp;lt;</code></td>
</tr>
<tr>
  <td align="center"><code>&amp;</code></td>
  <td><code>&amp;amp;&nbsp;</code></td>
</tr>
<tr>
  <td align="center"><code>&gt;</code></td>
  <td><code>&amp;gt;</code></td>
</tr>
</table>

<p>
For more information about
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
elements, see the following links:
<ul>
<li><a href="http://www.w3.org/TR/xmlschema-1/#element-annotation" target="_blank">http://www.w3.org/TR/xmlschema-1/#element-annotation</a></li>
<li><a href="http://www.w3schools.com/schema/el_annotation.asp" target="_blank">http://www.w3schools.com/schema/</a></li>
</ul>

<h2>
  <a name="rendering_line_breaks"></a>
  9.&nbsp; How to enable/disable interpreting line breaks in my comments?
</h2>

The comment text enclosed in a single
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element (see <a href="#adding_comments">How to add comments into my XML schema?</a>)
may contain any number of lines.
You may produce the new lines simply for convenience during writing that text.
<p>
However, you may also use the new lines as a way to format your comments.
In that case, most likely, you will want too see the same lines in the "Annotation"
sections of the generated documentation. Click on the following screenshot to see how this may look:
<blockquote>
<a href="javascript:popupWindow('images/p012.html',880,1128)"><img src="images/p012_s.gif" alt="XML Schema for XML Schemas, RTF, p.12" border="0"></a>
</blockquote>

That means that the generator must interpret the line breaks specified within the raw XML
with the markup coding appropriate to the given output format (e.g.
with "&lt;BR&gt;" in HTML or "\line" in RTF).
<p>
To tell the generator to do so, you should invoke the output
<a href="../doc.html#generator_gui.format_option_inspector">Format Option Inspector</a>
(by clicking the <b>&ldquo;Options&rdquo;</b> button in the
<a href="about.html#generator_gui">Generator Dialog</a>)
and select in it the <b>&ldquo;Render&nbsp;line&nbsp;breaks&rdquo;</b> option.
<p>
If you actually do not need to have the line breaks to be interpreted
(which may be especially true when you format your comments using <a href="#xhtml">XHTML</a>),
make sure that "Render&nbsp;line&nbsp;breaks" option is always unchecked.

<h2>
  <a name="xhtml"></a>
  10.&nbsp; How to format my comments using XHTML?
</h2>

Besides interpreting <a href="#rendering_line_breaks">multiline</a> text comments
<a href="#adding_comments">added</a> into your schema using
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
elements,
this XML Schema documentation generator supports a much more powerful way of formatting your texts and descriptions.
<p>
Now, within the
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
elements, rather than just plain text, you can specify a full-blown XHTML markup!

<h3>
  <a name="xhtml.about"></a>
  What is XHTML?
</h3>

XHTML is basically the old HTML which is well-formed enough to be a valid XML at the same time.
In particular, that means:
<ol>
<li class="mrg8">
  All HTML tags and their attributes become XHTML elements and attributes.
</li>
<li class="mrg8">
  All XHTML elements belong to "XHTML" namespace associated with the following URI:
  <blockquote class="mrg8">
    <code><b>http://www.w3.org/1999/xhtml</b></code>
  </blockquote>
</li>
<li class="mrg8">
  Unlike in HTML, each XHTML container element must always have both opening and closing tags:
  <blockquote class="mrg8">
    <code>&lt<i>tag</i>&gt ... &lt/<i>tag</i>&gt</code>
  </blockquote>
</li>
<li class="mrg8">
  Each XHTML element with empty content must be specified as this:
  <blockquote class="mrg8">
    <code>&lt<i>tag</i>/&gt</code>
  </blockquote>
  (Rather than simply <code>'&lt<i>tag</i>&gt'</code>, which would be valid in HTML.)
</li>
</ol>

In anything else, XHTML may be used the same as the normal HTML.
<p>
For more information about XHTML, see these links:
<ul>
<li><a href="http://www.w3.org/MarkUp/" target="_blank">http://www.w3.org/MarkUp/</a></li>
<li><a href="http://www.w3schools.com/xhtml/" target="_blank">http://www.w3schools.com/xhtml/</a></li>
</ul>

<h3>
  <a name="xhtml.usage"></a>
  How to use XHTML?
</h3>

Here is how XHTML can be used in an XML Schema annotation:
<p>
<TABLE BGCOLOR="#F5F5F5" CELLSPACING="0" CELLPADDING="7" BORDER="0" CLASS="brdr1">
<TR><TD CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:documentation</SPAN> <SPAN CLASS="f4"><u>xmlns</u></SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/1999/xhtml</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">h3</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">Complete List of all Salutations</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">h3</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f3">Allowed only three values:</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MR.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MS.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MRS&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:schema</SPAN><SPAN CLASS="f1">&gt;</SPAN>
</TD>
</TR>
</TABLE>
<p>
Here, the <b><code>xmlns</code></b> attribute specified in the start tag of the
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element switches the default namespace within it to XHTML. That means that any XML elements without namespace prefixes contained in that
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
will belong to the XHTML namespace.
Now, we can freely use ordinary HTML tags to format our comment!
<p>
The <code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element is not the only place where you can switch the default namespace.
You can equally do it in the start tag of any other element. At that, both that element and any other elements
contained in it (if they have no namespace prefixes) will be treated as belonging to the XHTML namespace.
For instance, the above example can be written also in the following way:
<p>
<TABLE BGCOLOR="#F5F5F5" CELLSPACING="0" CELLPADDING="7" BORDER="0" CLASS="brdr1">
<TR><TD>
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">div</SPAN> <SPAN CLASS="f4"><u>xmlns</u></SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/1999/xhtml</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">h3</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">Complete List of all Salutations</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">h3</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f3">Allowed only three values:</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p5"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MR.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p5"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MS.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p5"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MRS&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">div</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:schema</SPAN><SPAN CLASS="f1">&gt;</SPAN>
</TD>
</TR>
</TABLE>
<p>
The <b><code>&lt;div&gt;</code></b> element here is just a generic structure HTML element
and it encloses all the annotation text with the HTML markup.
<p>
However, switch the default namespace is not the only way. Alternatively, you can bind
the XHTML namespace URI to a certain arbitrary prefix (for instance, <code>"xhtml"</code>)
in the start tag of the very top XML schema definition element (that is the
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/schema.html" target="_blank">&lt;xs:schema&gt;</a></code>
element itself). Further, you should add that prefix to each HTML tag you use in your annotations.
Here is how our example will look in that case:
<p>
<TABLE BGCOLOR="#F5F5F5" CELLSPACING="0" CELLPADDING="7" BORDER="0" CLASS="brdr1">
<TR><TD>
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;</SPAN><SPAN CLASS="f4"><br><u>xmlns:xhtml</u></SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/1999/xhtml</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xhtml:h3</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">Complete List of all Salutations</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xhtml:h3</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f3">Allowed only three values:</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xhtml:ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MR.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MS.&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p4"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN><SPAN CLASS="f3">&quot;MRS&quot;</SPAN><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xhtml:li</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xhtml:ol</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:schema</SPAN><SPAN CLASS="f1">&gt;</SPAN>
</TD>
</TR>
</TABLE>
<p>
The <a href="about.html#xsddoc_templates">XSDDoc</a> templates
are designed so that they recognize the XHTML elements contained in
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
elements and process them appropriately.
<p>
In fact, the templates simply filter all XHTML tags and just reproduce them back with all namespace prefixes removed
(if any were used in the original comment source, as in the previous example).
So, the entire content of an
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element produces a piece of normal HTML, which is inserted directly into the generated
<a href="#gen_html">HTML output</a> or processed further, in the case of non-HTML output formats (see below).
Here is how such an HTML will look when generated from both of the above examples:
<p>
<table border="1" cellspacing="1" cellpadding="8">
<tr>
<td BGCOLOR="#F5F5F5">
<h3>Complete List of all Salutations</h3>
Allowed only three values:
<ol class="mrg80">
<li>"MR."</li>
<li>"MS."</li>
<li>"MRS"</li>
</ol>
</td></tr>
</table>
<p>
In the case of the <a href="#gen_rtf">RTF documentation</a> (generated using
<a href="about.html#XSDDoc.tpl"><code>XSDDoc.tpl</code></a> template),
the piece of HTML produced from the content of an
<code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/documentation.html" target="_blank">&lt;xs:documentation&gt;</a></code>
element is processed even further.
All HTML tags are parsed and interpreted with the proper formatting features available in RTF.
Almost all HTML tags (and their attributes) practically usable in documentation comments are processed in that way.
Here's the list of all supported HTML tags:
<p>
<table border="1" cellspacing="1" cellpadding="5">
<tr valign="top">
  <td><b>Text</b></td>
  <td>
    &lt;b&gt;, &lt;strong&gt;, &lt;i&gt;, &lt;em&gt;, &lt;code&gt;, &lt;tt&gt;, &lt;u&gt;,
    &lt;s&gt;, &lt;strike&gt;, &lt;sub&gt;, &lt;sup&gt;, &lt;font&gt;, &lt;br&gt;
  </td>
</tr>
<tr valign="top">
  <td><b>Paragraphs</b></td>
  <td>
    &lt;p&gt;, &lt;center&gt;, &lt;div&gt;, &lt;pre&gt;, &lt;h1&gt;, &lt;h2&gt;, &lt;h3&gt;,
    &lt;h4&gt;, &lt;h5&gt;, &lt;h6&gt;, &lt;blockquote&gt;
  </td>
</tr>
<tr valign="top">
  <td><b>Lists</b></td>
  <td>
    &lt;ul&gt;, &lt;ol&gt;, &lt;li&gt;, &lt;dl&gt;, &lt;dt&gt;, &lt;dd&gt;
  </td>
</tr>
<tr valign="top">
  <td><b>Table</b></td>
  <td>
    &lt;table&gt;, &lt;tr&gt;, &lt;td&gt;, &lt;th&gt;
  </td>
</tr>
<tr valign="top">
  <td><b>Other</b></td>
  <td>
    &lt;hr&gt;, &lt;img&gt;, &lt;a&gt;...&lt;/a&gt;
  </td>
</tr>
</table>
<p>
The result RTF output generated by such an annotation preformatted with <a href="#xhtml">XHTML</a>
may look as on the following screenshot (click to see the real size page preview):

<blockquote>
<a href="javascript:popupWindow('images/xhtml_ann_rtf1.html',880,1128)"><img src="images/xhtml_ann_rtf1_s.gif" alt="Using XHTML in XML Schema annotations (RTF demo)" border="0"></a>
</blockquote>

<h3>
  <a name="xhtml.images"></a>
  How to insert images?
</h3>

In addition to the rich formatting capabilities, XHTML allows you also
inserting images into your documentation.
To add an image in the annotation, you should use <code>&lt;img&gt;</code> tag.
Here is how this can be done:
<p>
<TABLE BGCOLOR="#F5F5F5" CELLSPACING="0" CELLPADDING="7" BORDER="0" CLASS="brdr1">
<TR><TD CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:documentation</SPAN> <SPAN CLASS="f4">xmlns</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/1999/xhtml</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f3">The "Valid XHTML 1.0 Strict" Icon:</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">p</SPAN><SPAN CLASS="f6"><SPAN CLASS="f1">/&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">img</SPAN> <SPAN CLASS="f2">src</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">http://www.w3.org/Icons/valid-xhtml10.png</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:documentation</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:annotation</SPAN><SPAN CLASS="f1">&gt;</SPAN>
</TD>
</TR>
</TABLE>
<p>
After processing such an annotation, the generator will produce the following fragment of
<a href="#gen_html">HTML</a>:
<p>
<table border="1" cellspacing="1" cellpadding="8">
<tr>
<td BGCOLOR="#F5F5F5">
The "Valid XHTML 1.0 Strict" Icon:
<p class="mrg8"></p>
<img src="images/valid-xhtml10.png">
</td></tr>
</table>
<p>
The images can also be inserted in the <a href="#gen_rtf">RTF</a> output (see the screenshot above).
<p>
Please note, the following
<a href="about.html#param_inspector">template parameters</a> and
<a href="../doc.html#generator_gui.output_format">output format options</a>
are important for processing of images:
<ul>
<li>
  <i>"Sections | Annotation | Process XHTML tags"</i> parameter
  (both <a href="about.html#XSDDocFrames.tpl"><code>XSDDocFrames.tpl</code></a>
  and <a href="about.html#XSDDoc.tpl"><code>XSDDoc.tpl</code></a>).
</li>
<li>
  <i>"Sections | Annotation | Include images"</i> parameter (both templates).
</li>
<li>
  <i>"Sections | Annotation | Copy images"</i> parameter (both templates).
</li>
<li>
  <i>"Store graphics in RTF"</i> option (<a href="#gen_rtf">RTF</a> output).
</li>
</ul>

See details below.

<h3>
  <a name="xhtml.params_and_options"></a>
  Parameters & options related to XHTML and images
</h3>

If you <a href="#xhtml.usage">use XHTML</a> to format your XML schema annotations,
when generating documentation, please pay attention to the following
<a href="about.html#param_inspector">template parameters</a>:
<ul>
<li>
  <b>&ldquo;Sections | Annotation | Process XHTML tags"</b> parameter
  (both <a href="about.html#XSDDocFrames.tpl"><code>XSDDocFrames.tpl</code></a>
  and <a href="about.html#XSDDoc.tpl"><code>XSDDoc.tpl</code></a>)
  should be <b><code>true</code></b>.
</li>
<li>
  <b>&ldquo;Sections | Annotation | Include images"</b> parameter (both templates)
  controls whether to include <a href="#xhtml.images">images</a> specified
  with <code>&lt;img&gt;</code> tags.
</li>
<li>
  <b>&ldquo;Sections | Annotation | Copy images"</b> parameter (both templates)
  should be <b><code>true</code></b>,
  when you generate <a href="#gen_html">HTML</a> output and want all <a href="#xhtml.images">images</a>
  specified in <code>&lt;img&gt;</code> tags to be automatically copied and stored along with
  the result documentation (rather than left referred from it by the original URLs).
</li>
<li>
  <b>&ldquo;Sections | XML Source | Remove Annotation"</b> parameter group (both templates)
  controls removing of
  <code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
  elements from the reproduced <a href="about.html#doc.xml_source">XML source</a>.
  You may want to exclude
  <code><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/annotation.html" target="_blank">&lt;xs:annotation&gt;</a></code>
  elements because when XHTML tags are used to format annotation texts, the full XML source of such elements may be
  so large that it will overwhelm anything else and it will be difficult to understand anything.
</li>
</ul>
and the following
<a href="../doc.html#generator_gui.output_format">output format options</a>:
<ul>
<li>
  <b>&ldquo;Render embedded HTML&rdquo;</b> option (all formats) should be <b><code>true</code></b>.
</li>
<li>
  <b>&ldquo;Render line breaks&rdquo;</b> option (all formats) should be <b><code>false</code></b>,
  unless you want your original line breaks to be interpreted along with your HTML markup.
</li>
<li>
  <b>&ldquo;Store graphics in RTF&rdquo;</b> option (<a href="#gen_rtf">RTF</a>)
  should be <b><code>true</code></b> to have all <a href="#xhtml.images">images</a> stored directly
  in the generated RTF file.
</li>
</ul>

<h2>
  <a name="invalid_doc"></a>
  11.&nbsp; There is some oddity in the documentation I've generated. What might be wrong?
</h2>

Your problem is that: You have generated a documentation by your XML schema(s) and
it appears that something is wrong in it. For instance, some hyperlinks lead
to wrong locations, others may be absent at all when they should be there and so on.
<p>
Most likely, the cause of all such odd things may be that some of your input
XML schemas are actually invalid (that is, they do not strictly comply with
<a href="http://www.w3.org/XML/Schema" target="_blank">W3C XML Schema</a>
specification).
<p>
<table border="1" cellspacing="1" cellpadding="6">
<tr><td bgcolor="#F5F5F5" class="inset">

A common mistake is specifying the schema's target namespace and
forgetting to set that namespace to be default within the
<code class="small"><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/schema.html" target="_blank">&lt;xs:schema&gt;</a></code>
element. For example, in the following schema definition:
<blockquote class="mrg8">
<div CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;</SPAN>
<br><SPAN CLASS="f2">targetNamespace</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">http://www.company.com/project</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f7">&lt;!-- Complex Type Definitions --&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:complexType</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">Account</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:sequence</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:element</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">NAME</SPAN><SPAN CLASS="f1">&quot;</SPAN> <SPAN CLASS="f2">type</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">acctholdername</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:sequence</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:complexType</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f7">&lt;!-- Simple Type Definitions --&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:simpleType</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">acctholdername</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:restriction</SPAN> <SPAN CLASS="f2">base</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">xs:string</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:minLength</SPAN> <SPAN CLASS="f2">value</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">1</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:maxLength</SPAN> <SPAN CLASS="f2">value</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">80</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:restriction</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:simpleType</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<SPAN CLASS="f1">&lt;/</SPAN><SPAN CLASS="f2">xs:schema</SPAN><SPAN CLASS="f1">&gt;</SPAN>
</div>
</blockquote>
the element <code class="small">'NAME'</code> specified within the complex type is supposed to have a simple type
<code class="small">'acctholdername'</code>, which is defined just below and belongs to the schema's target namespace
<code class="small">"http://www.company.com/project"</code>. However, the <code class="small">type</code> attribute of
<code class="small"><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/element_1.html" target="_blank">&lt;xs:element&gt;</a></code>
element requires a value of <code class="small"><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/simpleTypes/QName.html" target="_blank">xs:QName</a></code>
type, that is an XML qualified name. Since the default namespace was not assigned in that schema,
what that particular <code class="small">type</code> attribute actually refers to is the <code class="small">'acctholdername'</code> type
within the <i>global</i> namespace. Such a type has nothing to do with the simple type <code class="small">'acctholdername'</code>
defined in that schema and will be simply unknown here.
Hence, the whole schema is incorrect and the documentation generated by it will be incorrect too.
<p class="mrg8">
However, the situation can be easily fixed. All is needed is to set the default namespace
in the start tag of the
<code class="small"><a href="http://www.filigris.com/products/docflex_xml/xsddoc/examples/html/XMLSchema/schemas/XMLSchema_xsd/elements/schema.html" target="_blank">&lt;xs:schema&gt;</a></code>
element:
<blockquote class="mrg8">
<div CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;</SPAN><br>
<SPAN CLASS="f2">targetNamespace</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">http://www.company.com/project</SPAN><SPAN CLASS="f1">&quot;</SPAN><br>
<SPAN CLASS="f4"><u>xmlns</u></SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.company.com/project</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
</div>
</blockquote>
Alternatively, a custom namespace prefix may be used, for instance <code class="small">"prj"</code>:
<blockquote class="mrg8">
<div CLASS="f6">
<SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:schema</SPAN> <SPAN CLASS="f4">xmlns:xs</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.w3.org/2001/XMLSchema</SPAN><SPAN CLASS="f1">&quot;</SPAN><br>
<SPAN CLASS="f2">targetNamespace</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">http://www.company.com/project</SPAN><SPAN CLASS="f1">&quot;</SPAN><br>
<SPAN CLASS="f4"><u>xmlns:prj</u></SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f5">http://www.company.com/project</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN>
<DIV><SPAN CLASS="f2">...</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f7">&lt;!-- Complex Type Definitions --&gt;</SPAN></DIV>
<DIV CLASS="p1"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:complexType</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">Account</SPAN><SPAN CLASS="f1">&quot;&gt;</SPAN></DIV>
<DIV CLASS="p2"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:sequence</SPAN><SPAN CLASS="f1">&gt;</SPAN></DIV>
<DIV CLASS="p3"><SPAN CLASS="f1">&lt;</SPAN><SPAN CLASS="f2">xs:element</SPAN> <SPAN CLASS="f2">name</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3">NAME</SPAN><SPAN CLASS="f1">&quot;</SPAN> <SPAN CLASS="f2">type</SPAN><SPAN CLASS="f1">=&quot;</SPAN><SPAN CLASS="f3"><u>prj</u>:acctholdername</SPAN><SPAN CLASS="f1">&quot;/&gt;</SPAN></DIV>
</div>
</blockquote>
</td></tr>
</table>

<p>
In fact, <a href="about.html#xsddoc_templates">XSDDoc</a>
templates do not verify the validity of the input XML schemas.
The templates have been designed in assumption that the input XML schemas are correct.
When a schema is incorrect, certain documentation will still be generated.
However, what that documentation will be no one knows...
Actually, it may be even more incorrect than the source schema because which exactly
processing a particular invalid XML schema will spawn is difficult to predict.
<p>
So, before running the documentation generator, we suggest to verify your schemas(s) with
an appropriate tool.
<p>
For instance, you may use an online XML schema validator found by this link:
<a href="http://www.w3.org/2001/03/webdata/xsv" target="_blank">http://www.w3.org/2001/03/webdata/xsv</a>.
Otherwise, you can go to W3C XML Schema home page and look at the "Tools" section:
<a href="http://www.w3.org/XML/Schema#Tools" target="_blank">http://www.w3.org/XML/Schema#Tools</a>.
<p>
If all your schemas have passed the validation and the errors in the generated documentation
still persist, then, indeed, there may be something wrong in the templates (or elsewhere)...
In that case, please, let us know by sending a e-mail to:
<a href="mailto:contact@filigris.com">contact@filigris.com</a>.


<h2>
  <a name="xmlschema.resources"></a>
  12.&nbsp; Where can I learn more about XML schemas?
</h2>

We may suggest the following links:
<ul>
<li><a href="http://www.w3.org/XML/Schema" target="_blank">W3.org: W3C XML Schema</a></li>
<li><a href="http://en.wikipedia.org/wiki/XML_Schema" target="_blank">Wikipedia: XML Schema</a></li>
<li><a href="http://www.w3schools.com/schema/" target="_blank">W3Schools.com: XML Schema Tutorial</a></li>
<li><a href="http://www.xfront.com/xml-schema.html" target="_blank">xFront.com: XML Schema Tutorial</a></li>
<li><a href="http://www.xml.com/pub/a/2000/11/29/schemas/part1.html" target="_blank">XML.com: Using W3C XML Schema</a></li>
<li><a href="http://www.oracle.com/technology/" target="_blank">Oracle Technology Network</a>:
  <ul>
    <li><a href="http://www.oracle.com/technology/pub/articles/srivastava_namespaces.html" target="_blank">XML Schema: Understanding Namespaces</a></li>
    <li><a href="http://www.oracle.com/technology/pub/articles/srivastava_datatypes.html" target="_blank">XML Schema: Understanding Datatypes</a></li>
    <li><a href="http://www.oracle.com/technology/pub/articles/srivastava_structures.html" target="_blank">XML Schema: Understanding Structures</a></li>
  </ul>
</li>
<li><a href="http://www.xml.com/resourceguide/" target="_blank">XML.com: Resource Guide</a></li>
<li><a href="http://www.rpbourret.com/xml/XMLURLs.htm" target="_blank">Ronald Bourret: XML Links</a></li>
</ul>

Also, there is a good book (which we have been using ourselves from the very start):
<p>
<table cellspacing="0" cellpadding="0" border="0">
<tr valign="top">
<td><a href="http://www.oreilly.com/catalog/xmlschema/" target="_blank"><img src="images/xmlschema_book.gif" border="0" style="margin-right:10px"></a></td>
<td class="impr">
<b>XML Schema</b><br>by Eric van der Vlist
<p class="mrg8">
<table cellspacing="0" cellpadding="0" border="0">
<tr>
  <td class="impr">Publisher:&nbsp;</td>
  <td class="impr"><b>O'Reilly</b></td>
</tr>
<tr>
  <td class="impr">Pub Date:&nbsp;</td>
  <td class="impr"><b>June 2002</b></td>
</tr>
<tr>
  <td class="impr">ISBN:&nbsp;</td>
  <td class="impr"><b>0-596-00252-1</b></td>
</tr>
<tr>
  <td class="impr">Pages:&nbsp;</td>
  <td class="impr"><b>400</b></td>
</tr>
</table>
</td>
</tr>
</table>
<p>
The "Element Reference Guide" contained in that book gave us some important ideas of
how a good XML schema documentation should be organized and what it should include.


<p>
<hr>
<span class="impr">Copyright&copy; 2003-2007 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.<br>
To contact us, please visit
<a href="http://www.filigris.com">www.filigris.com</a> or e-mail to: <a href="mailto:contact@filigris.com">contact@filigris.com</a>
</span>
</p>

</body>

</html>
